home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2002 November / SGI IRIX Base Documentation 2002 November.iso / usr / share / catman / p_man / cat3c / pfmt.z / pfmt
Encoding:
Text File  |  2002-10-03  |  20.4 KB  |  330 lines

  1.  
  2.  
  3.  
  4. ppppffffmmmmtttt((((3333CCCC))))                                                              ppppffffmmmmtttt((((3333CCCC))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      _pppp_ffff_mmmm_tttt, _vvvv_pppp_ffff_mmmm_tttt -  display error message in standard format
  10.  
  11. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  12.      _####_iiii_nnnn_cccc_llll_uuuu_dddd_eeee _<<<<_pppp_ffff_mmmm_tttt_...._hhhh_>>>>
  13.  
  14.      _iiii_nnnn_tttt _pppp_ffff_mmmm_tttt_((((_FFFF_IIII_LLLL_EEEE _****_s_t_r_e_a_m_,,,, _llll_oooo_nnnn_gggg _f_l_a_g_s_,,,, _cccc_hhhh_aaaa_rrrr _****_f_o_r_m_a_t_,,,, _...._...._.... _////_**** _a_r_g_s _****_////_))))_;;;;
  15.  
  16.      _####_iiii_nnnn_cccc_llll_uuuu_dddd_eeee _<<<<_ssss_tttt_dddd_aaaa_rrrr_gggg_...._hhhh_>>>>
  17.      _####_iiii_nnnn_cccc_llll_uuuu_dddd_eeee _<<<<_pppp_ffff_mmmm_tttt_...._hhhh_>>>>
  18.  
  19.      _iiii_nnnn_tttt _vvvv_pppp_ffff_mmmm_tttt_((((_FFFF_IIII_LLLL_EEEE _****_s_t_r_e_a_m_,,,, _llll_oooo_nnnn_gggg _f_l_a_g_s_,,,, _cccc_hhhh_aaaa_rrrr _****_f_o_r_m_a_t_,,,, _vvvv_aaaa______llll_iiii_ssss_tttt _a_p_))))_;;;;
  20.  
  21. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  22.    ppppffffmmmmtttt
  23.      _pppp_ffff_mmmm_tttt uses a format string for _pppp_rrrr_iiii_nnnn_tttt_ffff style formatting of _a_r_g_s.  The
  24.      output is displayed on _s_t_r_e_a_m.  _pppp_ffff_mmmm_tttt encapsulates the output in the
  25.      standard error message format.  If the environment variable _NNNN_OOOO_MMMM_SSSS_GGGG_LLLL_AAAA_BBBB_EEEE_LLLL is
  26.      set it will turn off message labels.  Another environment variable
  27.      _NNNN_OOOO_MMMM_SSSS_GGGG_SSSS_EEEE_VVVV_EEEE_RRRR_IIII_TTTT_YYYY will also turn off message severity.  These two variable
  28.      can be set to turn off part of pfmt's error message fields.
  29.  
  30.      If the _pppp_rrrr_iiii_nnnn_tttt_ffff format string is to be retrieved from a message database,
  31.      the _f_o_r_m_a_t argument must have the following structure:
  32.  
  33.           _[[[[_[[[[_c_a_t_a_l_o_g_::::_]]]]_m_s_g_n_u_m_::::_]]]]_d_e_f_m_s_g.
  34.  
  35.      If _MMMM_MMMM______NNNN_OOOO_GGGG_EEEE_TTTT is specified, only the _d_e_f_m_s_g part must be specified.
  36.  
  37.      _c_a_t_a_l_o_g indicates the message database that contains the localized
  38.      version of the format string.  _c_a_t_a_l_o_g must be limited to 14 characters.
  39.      These characters must be selected from a set of all characters values,
  40.      excluding _\\\\_0000 (null) and the ASCII codes for _//// (slash) and _:::: (colon).
  41.  
  42.      _m_s_g_n_u_m must be a positive number that indicates the index of the string
  43.      into the message database.
  44.  
  45.      If _c_a_t_a_l_o_g does not exist in the locale (specified by the last call to
  46.      _ssss_eeee_tttt_llll_oooo_cccc_aaaa_llll_eeee using the _LLLL_CCCC______AAAA_LLLL_LLLL or _LLLL_CCCC______MMMM_EEEE_SSSS_SSSS_AAAA_GGGG_EEEE_SSSS categories), or if the message
  47.      number is out of bounds, _pppp_ffff_mmmm_tttt attempts to retrieve the message from the _CCCC
  48.      locale.  If this second retrieval fails, _pppp_ffff_mmmm_tttt uses the _d_e_f_m_s_g part of the
  49.      _f_o_r_m_a_t argument.
  50.  
  51.      If _c_a_t_a_l_o_g is omitted, _pppp_ffff_mmmm_tttt attempts to retrieve the string from the
  52.      default catalog specified by the last call to _ssss_eeee_tttt_cccc_aaaa_tttt.  In this case, the
  53.      _f_o_r_m_a_t argument has the following structure:
  54.  
  55.           _m_s_g_n_u_m_::::_d_e_f_m_s_g.
  56.  
  57.      _pppp_ffff_mmmm_tttt outputs _MMMM_eeee_ssss_ssss_aaaa_gggg_eeee _nnnn_oooo_tttt _ffff_oooo_uuuu_nnnn_dddd_!!!!_!!!!\_n as the format string if:
  58.  
  59.  
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. ppppffffmmmmtttt((((3333CCCC))))                                                              ppppffffmmmmtttt((((3333CCCC))))
  71.  
  72.  
  73.  
  74.           - _c_a_t_a_l_o_g is not a valid catalog name as defined above
  75.  
  76.           - no catalog is specified (either explicitly or via _ssss_eeee_tttt_cccc_aaaa_tttt)
  77.  
  78.           - _m_s_g_n_u_m is not a positive number,
  79.  
  80.           - no message could be retrieved and _d_e_f_m_s_g was omitted
  81.  
  82.      The _f_l_a_g_s determine the type of output (i.e., whether the _f_o_r_m_a_t should
  83.      be interpreted as is or encapsulated in the standard message format), and
  84.      the access to message catalogs to retrieve a localized version of _f_o_r_m_a_t.
  85.  
  86.      The _f_l_a_g_s are composed of several groups, and can take the following
  87.      values (one from each group):
  88.  
  89.      _O_u_t_p_u_t _f_o_r_m_a_t _c_o_n_t_r_o_l
  90.  
  91.           _MMMM_MMMM______NNNN_OOOO_SSSS_TTTT_DDDD    do not use the standard message format, interpret _f_o_r_m_a_t
  92.                       as a _pppp_rrrr_iiii_nnnn_tttt_ffff _f_o_r_m_a_t.  Only _c_a_t_a_l_o_g _a_c_c_e_s_s _c_o_n_t_r_o_l _f_l_a_g_s
  93.                       should be specified if _MMMM_MMMM______NNNN_OOOO_SSSS_TTTT_DDDD is used; all other flags
  94.                       will be ignored.
  95.  
  96.           _MMMM_MMMM______SSSS_TTTT_DDDD      output using the standard message format (default, value
  97.                       0).
  98.  
  99.      _C_a_t_a_l_o_g _a_c_c_e_s_s _c_o_n_t_r_o_l
  100.  
  101.           _MMMM_MMMM______NNNN_OOOO_GGGG_EEEE_TTTT    do not retrieve a localized version of _f_o_r_m_a_t.  In this
  102.                       case, only the _d_e_f_m_s_g part of the _f_o_r_m_a_t is specified.
  103.  
  104.           _MMMM_MMMM______GGGG_EEEE_TTTT      retrieve a localized version of _f_o_r_m_a_t, from the
  105.                       _c_a_t_a_l_o_g, using _m_s_g_n_u_m as the index and _d_e_f_m_s_g as the
  106.                       default message (default, value 0).
  107.  
  108.      _S_e_v_e_r_i_t_y (_s_t_a_n_d_a_r_d _m_e_s_s_a_g_e _f_o_r_m_a_t _o_n_l_y)
  109.  
  110.           _MMMM_MMMM______HHHH_AAAA_LLLL_TTTT     generates a localized version of _HHHH_AAAA_LLLL_TTTT.
  111.  
  112.           _MMMM_MMMM______EEEE_RRRR_RRRR_OOOO_RRRR    generates a localized version of _EEEE_RRRR_RRRR_OOOO_RRRR (default, value
  113.                       0).
  114.  
  115.           _MMMM_MMMM______WWWW_AAAA_RRRR_NNNN_IIII_NNNN_GGGG  generates a localized version of _WWWW_AAAA_RRRR_NNNN_IIII_NNNN_GGGG.
  116.  
  117.           _MMMM_MMMM______IIII_NNNN_FFFF_OOOO     generates a localized version of _IIII_NNNN_FFFF_OOOO.
  118.  
  119.           Additional severities can be defined.  Add-on severities can be
  120.           defined with number-string pairs with numeric values from the range
  121.           [5-255], using _aaaa_dddd_dddd_ssss_eeee_vvvv(3C).  The numeric value ORed with other _f_l_a_g_s
  122.           will generate the specified severity.
  123.  
  124.  
  125.  
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. ppppffffmmmmtttt((((3333CCCC))))                                                              ppppffffmmmmtttt((((3333CCCC))))
  137.  
  138.  
  139.  
  140.           If the severity is not defined, _pppp_ffff_mmmm_tttt uses the string _SSSS_EEEE_VVVV_====_N where _N
  141.           is replaced by the integer severity value passed in _f_l_a_g_s.
  142.  
  143.           Multiple severities passed in _f_l_a_g_s will not be detected as an
  144.           error.  Any combination of severities will be summed and the numeric
  145.           value will cause the display of either a severity string (if
  146.           defined) or the string _SSSS_EEEE_VVVV_====_N (if undefined).
  147.  
  148.      _A_c_t_i_o_n
  149.  
  150.           _MMMM_MMMM______AAAA_CCCC_TTTT_IIII_OOOO_NNNN   specifies an action message.  Any severity value is
  151.                       superseded and replaced by a localized version of _TTTT_OOOO
  152.                       _FFFF_IIII_XXXX.
  153.  
  154.    SSSSttttaaaannnnddddaaaarrrrdddd EEEErrrrrrrroooorrrr MMMMeeeessssssssaaaaggggeeee FFFFoooorrrrmmmmaaaatttt
  155.      _pppp_ffff_mmmm_tttt displays error messages in the following format:
  156.  
  157.           _l_a_b_e_l_:::: _s_e_v_e_r_i_t_y_:::: _t_e_x_t
  158.  
  159.      If no _l_a_b_e_l was defined by a call to _ssss_eeee_tttt_llll_aaaa_bbbb_eeee_llll, the message is displayed
  160.      in the format:
  161.  
  162.           _s_e_v_e_r_i_t_y_:::: _t_e_x_t
  163.  
  164.      If _pppp_ffff_mmmm_tttt is called twice to display an error message and a helpful _a_c_t_i_o_n
  165.      or recovery message, the output can look like:
  166.  
  167.           _l_a_b_e_l_:::: _s_e_v_e_r_i_t_y_:::: _t_e_x_t
  168.           _l_a_b_e_l_:::: _TTTT_OOOO _FFFF_IIII_XXXX_:::: _t_e_x_t
  169.  
  170.    vvvvppppffffmmmmtttt
  171.      _vvvv_pppp_ffff_mmmm_tttt is the same as _pppp_ffff_mmmm_tttt except that instead of being called with a
  172.      variable number of arguments, it is called with an argument list as
  173.      defined by the _ssss_tttt_dddd_aaaa_rrrr_gggg_...._hhhh header file.
  174.  
  175.      The _ssss_tttt_dddd_aaaa_rrrr_gggg_...._hhhh header file defines the type _vvvv_aaaa______llll_iiii_ssss_tttt and a set of macros for
  176.      advancing through a list of arguments whose number and types may vary.
  177.      The argument _a_p to _vvvv_pppp_ffff_mmmm_tttt is of type _vvvv_aaaa______llll_iiii_ssss_tttt.  This argument is used with
  178.      the _ssss_tttt_dddd_aaaa_rrrr_gggg_...._hhhh header file macros _vvvv_aaaa______ssss_tttt_aaaa_rrrr_tttt, _vvvv_aaaa______aaaa_rrrr_gggg and _vvvv_aaaa______eeee_nnnn_dddd [see
  179.      _vvvv_aaaa______ssss_tttt_aaaa_rrrr_tttt, _vvvv_aaaa______aaaa_rrrr_gggg, and _vvvv_aaaa______eeee_nnnn_dddd in _ssss_tttt_dddd_aaaa_rrrr_gggg(5)].  The EXAMPLE sections below
  180.      show their use.
  181.  
  182.      The macro _vvvv_aaaa______aaaa_llll_iiii_ssss_tttt is used as the parameter list in a function definition
  183.      as in the function called _eeee_rrrr_rrrr_oooo_rrrr in the example below.  The macro
  184.      _vvvv_aaaa______ssss_tttt_aaaa_rrrr_tttt_((((_a_p_,,,, _)))), where _a_p is of type _vvvv_aaaa______llll_iiii_ssss_tttt, must be called before any
  185.      attempt to traverse and access unnamed arguments.  Calls to _vvvv_aaaa______aaaa_rrrr_gggg_((((_a_p_,,,,
  186.      _a_t_y_p_e_)))) traverse the argument list.  Each execution of _vvvv_aaaa______aaaa_rrrr_gggg expands to
  187.      an expression with the value and type of the next argument in the list
  188.      _a_p, which is the same object initialized by _vvvv_aaaa______ssss_tttt_aaaa_rrrr_tttt.  The argument _a_t_y_p_e
  189.      is the type that the returned argument is expected to be.  The _vvvv_aaaa______eeee_nnnn_dddd_((((_a_p_))))
  190.      macro must be invoked when all desired arguments have been accessed.
  191.      [The argument list in _a_p can be traversed again if _vvvv_aaaa______ssss_tttt_aaaa_rrrr_tttt is called
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202. ppppffffmmmmtttt((((3333CCCC))))                                                              ppppffffmmmmtttt((((3333CCCC))))
  203.  
  204.  
  205.  
  206.      again after _vvvv_aaaa______eeee_nnnn_dddd.]  In the example below, _vvvv_aaaa______aaaa_rrrr_gggg is executed first to
  207.      retrieve the format string passed to _eeee_rrrr_rrrr_oooo_rrrr.  The remaining _eeee_rrrr_rrrr_oooo_rrrr
  208.      arguments, _a_r_g_1, _a_r_g_2, ..., are given to _vvvv_pppp_ffff_mmmm_tttt in the argument _a_p.
  209.  
  210. EEEEXXXXAAAAMMMMPPPPLLLLEEEESSSS
  211.    ppppffffmmmmtttt eeeexxxxaaaammmmpppplllleeee 1111
  212.      _ssss_eeee_tttt_llll_aaaa_bbbb_eeee_llll_((((_""""_UUUU_XXXX_::::_tttt_eeee_ssss_tttt_""""_))))_;;;;
  213.      _pppp_ffff_mmmm_tttt_((((_ssss_tttt_dddd_eeee_rrrr_rrrr_,,,, _MMMM_MMMM______EEEE_RRRR_RRRR_OOOO_RRRR_,,,, _""""_tttt_eeee_ssss_tttt_::::_2222_::::_CCCC_aaaa_nnnn_nnnn_oooo_tttt _oooo_pppp_eeee_nnnn _ffff_iiii_llll_eeee_:::: _%%%%_ssss_\\\\_nnnn_""""_,,,,
  214.        _ssss_tttt_rrrr_eeee_rrrr_rrrr_oooo_rrrr_((((_eeee_rrrr_rrrr_nnnn_oooo_))))_))))_;;;;
  215.  
  216.      displays the message:
  217.  
  218.      _UUUU_XXXX_::::_tttt_eeee_ssss_tttt_:::: _EEEE_RRRR_RRRR_OOOO_RRRR_:::: _CCCC_aaaa_nnnn_nnnn_oooo_tttt _oooo_pppp_eeee_nnnn _ffff_iiii_llll_eeee_:::: _NNNN_oooo _ssss_uuuu_cccc_hhhh _ffff_iiii_llll_eeee _oooo_rrrr _dddd_iiii_rrrr_eeee_cccc_tttt_oooo_rrrr_yyyy
  219.  
  220.    ppppffffmmmmtttt eeeexxxxaaaammmmpppplllleeee 2222
  221.      _ssss_eeee_tttt_llll_aaaa_bbbb_eeee_llll_((((_""""_UUUU_XXXX_::::_tttt_eeee_ssss_tttt_""""_))))_;;;;
  222.      _ssss_eeee_tttt_cccc_aaaa_tttt_((((_""""_tttt_eeee_ssss_tttt_""""_))))_;;;;
  223.      _pppp_ffff_mmmm_tttt_((((_ssss_tttt_dddd_eeee_rrrr_rrrr_,,,, _MMMM_MMMM______EEEE_RRRR_RRRR_OOOO_RRRR_,,,, _""""_::::_1111_0000_::::_SSSS_yyyy_nnnn_tttt_aaaa_xxxx _eeee_rrrr_rrrr_oooo_rrrr_\\\\_nnnn_""""_))))_;;;;
  224.      _pppp_ffff_mmmm_tttt_((((_ssss_tttt_dddd_eeee_rrrr_rrrr_,,,, _MMMM_MMMM______AAAA_CCCC_TTTT_IIII_OOOO_NNNN_,,,, _""""_::::_5555_5555_::::_UUUU_ssss_aaaa_gggg_eeee _...._...._...._\\\\_nnnn_""""_))))_;;;;
  225.  
  226.      displays the message
  227.  
  228.      _UUUU_XXXX_::::_tttt_eeee_ssss_tttt_:::: _EEEE_RRRR_RRRR_OOOO_RRRR_:::: _SSSS_yyyy_nnnn_tttt_aaaa_xxxx _eeee_rrrr_rrrr_oooo_rrrr
  229.      _UUUU_XXXX_::::_tttt_eeee_ssss_tttt_:::: _TTTT_OOOO _FFFF_IIII_XXXX_:::: _UUUU_ssss_aaaa_gggg_eeee _...._...._....
  230.  
  231.    vvvvppppffffmmmmtttt eeeexxxxaaaammmmpppplllleeee
  232.      The following demonstrates how _vvvv_pppp_ffff_mmmm_tttt could be used to write an _eeee_rrrr_rrrr_oooo_rrrr
  233.      routine:
  234.  
  235.           _####_iiii_nnnn_cccc_llll_uuuu_dddd_eeee _<<<<_pppp_ffff_mmmm_tttt_...._hhhh_>>>>
  236.           _####_iiii_nnnn_cccc_llll_uuuu_dddd_eeee _<<<<_ssss_tttt_dddd_aaaa_rrrr_gggg_...._hhhh_>>>>
  237.           _.... _.... _....
  238.           _////_****
  239.            _****   _eeee_rrrr_rrrr_oooo_rrrr _ssss_hhhh_oooo_uuuu_llll_dddd _bbbb_eeee _cccc_aaaa_llll_llll_eeee_dddd _llll_iiii_kkkk_eeee
  240.            _****         _eeee_rrrr_rrrr_oooo_rrrr_((((_ffff_oooo_rrrr_mmmm_aaaa_tttt_,,,, _aaaa_rrrr_gggg_1111_,,,, _...._...._...._))))_;;;;
  241.            _****_////
  242.           _vvvv_oooo_iiii_dddd _eeee_rrrr_rrrr_oooo_rrrr_((((_cccc_oooo_nnnn_ssss_tttt _cccc_hhhh_aaaa_rrrr _****_ffff_oooo_rrrr_mmmm_aaaa_tttt_,,,, _...._...._...._))))
  243.           _{{{{
  244.               _vvvv_aaaa______llll_iiii_ssss_tttt _aaaa_pppp_;;;;
  245.               _vvvv_aaaa______ssss_tttt_aaaa_rrrr_tttt_((((_aaaa_pppp_,,,, _))))_;;;;
  246.               _((((_vvvv_oooo_iiii_dddd_)))) _vvvv_pppp_ffff_mmmm_tttt_((((_ssss_tttt_dddd_eeee_rrrr_rrrr_,,,, _MMMM_MMMM______EEEE_RRRR_RRRR_OOOO_RRRR_,,,, _ffff_oooo_rrrr_mmmm_aaaa_tttt_,,,, _aaaa_pppp_))))_;;;;
  247.               _vvvv_aaaa______eeee_nnnn_dddd_((((_aaaa_pppp_))))_;;;;
  248.               _((((_vvvv_oooo_iiii_dddd_)))) _aaaa_bbbb_oooo_rrrr_tttt_((((_))))_;;;;
  249.           _}}}}
  250.  
  251. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  252.      _pppp_ffff_mmmm_tttt(1), _aaaa_dddd_dddd_ssss_eeee_vvvv(3C), _gggg_eeee_tttt_tttt_xxxx_tttt(3C), _llll_ffff_mmmm_tttt(3C), _ssss_eeee_tttt_cccc_aaaa_tttt(3C), _ssss_eeee_tttt_llll_aaaa_bbbb_eeee_llll(3C),
  253.      _ssss_eeee_tttt_llll_oooo_cccc_aaaa_llll_eeee(3C), _pppp_rrrr_iiii_nnnn_tttt_ffff(3S), _eeee_nnnn_vvvv_iiii_rrrr_oooo_nnnn(5), _ssss_tttt_dddd_aaaa_rrrr_gggg(5).
  254.  
  255.  
  256.  
  257.  
  258.  
  259.  
  260.                                                                         PPPPaaaaggggeeee 4444
  261.  
  262.  
  263.  
  264.  
  265.  
  266.  
  267. ppppffffmmmmtttt((((3333CCCC))))                                                              ppppffffmmmmtttt((((3333CCCC))))
  268.  
  269.  
  270.  
  271. DDDDIIIIAAAAGGGGNNNNOOOOSSSSTTTTIIIICCCCSSSS
  272.      On success, _pppp_ffff_mmmm_tttt and _vvvv_pppp_ffff_mmmm_tttt return the number of bytes transmitted.  On
  273.      failure, they return a negative value:
  274.  
  275.      -1   write error to _s_t_r_e_a_m
  276.  
  277.  
  278.  
  279.  
  280.  
  281.  
  282.  
  283.  
  284.  
  285.  
  286.  
  287.  
  288.  
  289.  
  290.  
  291.  
  292.  
  293.  
  294.  
  295.  
  296.  
  297.  
  298.  
  299.  
  300.  
  301.  
  302.  
  303.  
  304.  
  305.  
  306.  
  307.  
  308.  
  309.  
  310.  
  311.  
  312.  
  313.  
  314.  
  315.  
  316.  
  317.  
  318.  
  319.  
  320.  
  321.  
  322.  
  323.  
  324.  
  325.  
  326.                                                                         PPPPaaaaggggeeee 5555
  327.  
  328.  
  329.  
  330.